// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_CPDF_STRING_H_
#define CORE_FPDFAPI_PARSER_CPDF_STRING_H_

#include "core/fpdfapi/parser/cpdf_object.h"
#include "core/fxcrt/fx_string.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/span.h"
#include "core/fxcrt/string_pool_template.h"
#include "core/fxcrt/weak_ptr.h"

class CPDF_String final : public CPDF_Object {
 public:
  CONSTRUCT_VIA_MAKE_RETAIN;

  // Used as a placeholder to differentiate constructors.
  enum class DataType { kIsHex };

  // CPDF_Object:
  Type GetType() const override;
  RetainPtr<CPDF_Object> Clone() const override;
  ByteString GetString() const override;
  WideString GetUnicodeText() const override;
  void SetString(const ByteString& str) override;
  CPDF_String* AsMutableString() override;
  bool WriteTo(IFX_ArchiveStream* archive,
               const CPDF_Encryptor* encryptor) const override;

  bool IsHex() const { return output_is_hex_; }
  ByteString EncodeString() const;

 private:
  CPDF_String();
  CPDF_String(WeakPtr<ByteStringPool> pool,
              pdfium::span<const uint8_t> data,
              DataType is_hex);
  CPDF_String(WeakPtr<ByteStringPool> pool, const ByteString& str);
  CPDF_String(WeakPtr<ByteStringPool> pool, WideStringView str);
  ~CPDF_String() override;

  ByteString data_;
  bool output_is_hex_ = false;
};

inline CPDF_String* ToString(CPDF_Object* obj) {
  return obj ? obj->AsMutableString() : nullptr;
}

inline const CPDF_String* ToString(const CPDF_Object* obj) {
  return obj ? obj->AsString() : nullptr;
}

inline RetainPtr<const CPDF_String> ToString(RetainPtr<const CPDF_Object> obj) {
  return RetainPtr<const CPDF_String>(ToString(obj.Get()));
}

#endif  // CORE_FPDFAPI_PARSER_CPDF_STRING_H_
`CPDF_String` 类用于表示和操作 PDF 字符串对象，以下是这个类提供的接口功能：

### 类 `CPDF_String`

#### 构造函数与析构函数
1. * *CPDF_String() * *:
-默认构造函数。

2. * *CPDF_String(WeakPtr<ByteStringPool> pool, pdfium::span<const uint8_t> data, DataType is_hex) * *:
  -使用字节数据和数据类型（是否为十六进制）构造 `CPDF_String` 对象。

  3. * *CPDF_String(WeakPtr<ByteStringPool> pool, const ByteString & str) * *:
-使用 `ByteString` 构造 `CPDF_String`。

4. * *CPDF_String(WeakPtr<ByteStringPool> pool, WideStringView str) * *:
-使用 `WideStringView` 构造 `CPDF_String`。

5. * *~CPDF_String() * *:
-析构函数，用于销毁 `CPDF_String` 实例。

#### CPDF_Object 的重载方法
6. * *Type GetType() const override * *:
-获取对象类型。

7. * *RetainPtr<CPDF_Object> Clone() const override * *:
  -克隆 `CPDF_String` 对象。

  8. * *ByteString GetString() const override * *:
-获取字符串的 `ByteString` 表示。

9. * *WideString GetUnicodeText() const override * *:
-获取字符串的 Unicode 表示。

10. * *void SetString(const ByteString & str) override * *:
  -设置字符串内容。

  11. * *CPDF_String * AsMutableString() override * *:
  -获取可变的 `CPDF_String` 指针。

  12. * *bool WriteTo(IFX_ArchiveStream * archive, const CPDF_Encryptor * encryptor) const override * *:
-将字符串写入到流中，并可能使用加密器。

#### 其他方法
13. * *bool IsHex() const** :
  -检查字符串是否以十六进制格式输出。

  14. * *ByteString EncodeString() const** :
  -获取编码后的字符串。

  #### 实用函数
  15. * *ToString(CPDF_Object * obj) * *:
  -将 `CPDF_Object` 转换为 `CPDF_String` 指针，若对象为 `nullptr` 返回 `nullptr`。

  16. * *ToString(const CPDF_Object * obj) * *:
-将常量 `CPDF_Object` 转换为常量 `CPDF_String` 指针，若对象为 `nullptr` 返回 `nullptr`。

17. * *ToString(RetainPtr<const CPDF_Object> obj) * *:
-将常量智能指针 `CPDF_Object` 转换为 `CPDF_String` 的智能指针。

这些接口功能在 PDFium 中用于表示和处理 PDF 文档中的字符串，包括支持对字符串内容的设置、类型检查、克隆、编码，以及支持将字符串写出到文件流等。